time skipping fast forward by feiyang3cat · Pull Request #786 · temporalio/api

feiyang3cat · 2026-05-22T22:14:24Z

What changed?

Removed obsolete fields — safe to delete as this feature has not been released (disable compatibility checking temporarily)
Renamed bound to fast forward to define the concept from the perspective of users' behavior
Add disable_propagation_for_child to give users a way to stop propagation
Add update_time to UpdateWorkflowExecutionOptionsRequest
Moving TimeSkippingConfig from workflow path to common path

Why?

for 1) make the API cleaner
for 2) a neat name to reduce misunderstanding
for 3) a child workflow is a different execution and has its own virtual clock, and users may need an option to change the default propagation behavior
for 4) this can be used when SDK verify the time in TimeSkippingTransitionedEvent match the sleep duration
for 5) other executions like schedulers will also use the config

Breaking changes

removed the feature maxSkippedDuration-> the server has already implemented this feature need to delete the code first
restructured the maxElapsedDurationto fast_forward-> the server need to do renaming

Server PR
temporalio/temporal#10576

GregoryTravis · 2026-06-02T20:09:49Z

        }
      },
-      "description": "Configuration for time skipping during a workflow execution.\nWhen enabled, virtual time advances automatically whenever there is no in-flight work.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,\nand possibly other features added in the future.\nUser timers are not classified as in-flight work and will be skipped over.\nWhen time advances, it skips to the earlier of the next user timer or the configured bound, if either exists.\n\nPropagation behavior of time skipping:\nThe enabled flag, bound fields, and accumulated skipped duration are propagated to related executions as follows:\n(1) Child workflows and continue-as-new: both the configuration and the accumulated skipped duration are\n    inherited from the current execution. The configured bound is shared between the inherited skipped\n    duration and any additional duration skipped by the new run.\n(2) Retry and cron: the configuration and accumulated skipped duration are inherited as recorded when the\n    current workflow started; the accumulated skipped duration of the current run is not propagated.\n(3) Reset: the new run retains the time-skipping configuration of the current execution. Because reset replays\n    all events up to the reset point and re-applies any UpdateWorkflowExecutionOptions changes made after that\n    point, the resulting run ends up with the same final time-skipping configuration as the previous run."
+      "description": "The configuration for time skipping of a workflow execution (a chain of runs including retries, cron, continue-as-new).\nWhen time skipping is enabled, virtual time advances automatically whenever there is no in-flight work.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,\nand possibly other features added in the future.\nUser timers are not classified as in-flight work and will be skipped over; the virtual clock may also skip to the\ntime point of the registered sleep when there is no in-flight work.\n\nFor child workflows, by default, if the parent execution is skipping time, the child execution will also skip time,\nbut the parent's sleep won't affect the child execution. A flag is provided to disable propagation of the\n\"enabled\" flag to child workflows; regardless of that flag, a child workflow inherits the virtual time from the\nparent execution as its start time."


"to the time point of the registered sleep" -- does this mean to end point of the sleep period?

oh I see, this is better expression. yes. will change to "to the end point of the sleep period"

and I think I may need to add another thing is if the workflow execution (the whole chain of runs) completes before having a chance to skip time, the sleep may never take place -> check this example

GregoryTravis · 2026-06-02T20:12:53Z

+        "sleep": {
          "type": "string",
-          "description": "Maximum total virtual time that can be skipped."
+          "description": "Optionally register a sleep for the current workflow execution.\nWhen the sleep completes, time skipping is disabled and this action is recorded in\nthe WorkflowExecutionTimeSkippingTransitionedEvent, but it can be re-enabled by\nsetting `enabled` to true via UpdateWorkflowExecutionOptions.\nThe current workflow execution is a chain of runs (retries, cron, continue-as-new);\nchild workflows are separate executions, so this sleep won't affect them."


Is the implication here that the sleep will actually take place, and not be skipped?

yeah, totally, to be specific sleep counts both natural time passing and time skipping.

for example, the user calls sleep(1h) at 10am, and then the sleep is expected to take place in 11am if the workflow execution hasn't completed. And at 11am (virtual workflow time) the sleep takes place, but for the past 1hour the workflow may takes 30 minutes busy with activities (and this is real 30 minutes), and then waiting for some user timer/condition so we skip 30min(this is skipped) to fire the 1hour.

let me write some sleep examples

Sushisource · 2026-06-08T18:47:19Z

    google.protobuf.Timestamp target_time = 1;

-    // when true, time skipping was disabled automatically due to a bound being reached.
+    // When true, time skipping has been disabled automatically due to the fast_forward completing.


Suggested change

// When true, time skipping has been disabled automatically due to the fast_forward completing.

// When true, time skipping has been disabled automatically due to a call to fast_forward completing.

why do we need to add "a call" in this comment as there won't be any extra calls from the client side to disable it ?

"a call" here refers to the call that initiated the fast forward

get it. updated.

Sushisource · 2026-06-08T18:50:17Z

+
+    // The Workflow Execution time when the options were updated. When time skipping is
+    // enabled, this is the workflow's virtual time rather than wall-clock time.
+    google.protobuf.Timestamp update_time = 2;


How does this get used? Does SDK need to use this?

I think so but it is just a refinement/enhancement that when SDK checks the time skipping event it can re-verifies the time is correct. this is only needed in edgy case:
-> the user set fast-forward 2hours using SDK and waiting on it (1)
-> and the user issues another request to change it to 4hours (2)
-> and when client (1) finds the time skipping transitioned event it has a way to know it is a correct time to return

Can you go into more details what would happen in those edge cases (if fast-forward is updated to 2h before and after another user issues a request to update to 4h). From reading the server PR, I thought the fast-forward time is replace (either you will skip by 2h or 4h depending on which one comes first). How does the update_time helps there

(1) fast-forward is updated to 2h (update_time = A) before and after another user issues a request to update to 1h (update_time = B) assuming the 2h fast-forward hasn't taken place
(2) fast-forward takes place in B+1h as we only allows one fast forward in time skipping
(3) the user calling A+2h is still using SDK function to wait for the TimeSkippingTransitionedEvent and not the event comes, if SDK doesn't check the event it doesn't know the time it will think A+2h has arrived. if the user has update_time A it can check if the event time = update_time + duration

ok, so it will just sleep for the remaining of the 1h?

have resolved in huddle

simvlad · 2026-06-08T22:52:16Z

-        // (-- api-linter: core::0142::time-field-names=disabled --)
-        google.protobuf.Duration max_elapsed_duration = 5;
-    }
+    // Optionally fast-forward the current workflow execution to this point in time.


I don't think this should say "point in time", since this is a duration.

simvlad · 2026-06-08T23:56:51Z

+
+    // The Workflow Execution time when the options were updated. When time skipping is
+    // enabled, this is the workflow's virtual time rather than wall-clock time.
+    google.protobuf.Timestamp update_time = 2;


Can you go into more details what would happen in those edge cases (if fast-forward is updated to 2h before and after another user issues a request to update to 4h). From reading the server PR, I thought the fast-forward time is replace (either you will skip by 2h or 4h depending on which one comes first). How does the update_time helps there

simvlad

Looks good from server side

simvlad · 2026-06-10T20:59:09Z

 	mkdir $(PROTO_OUT)

 ##### Compile proto files for go #####
-grpc: buf-lint api-linter buf-breaking clean go-grpc fix-path


intentional?

oh yeah, I learnt that the current process to delete deprecated fields is to allow breaking and add this back in the next PR.

simvlad · 2026-06-10T21:44:04Z

+    // setting `enabled` to true via UpdateWorkflowExecutionOptions.
+    // The current workflow execution is a chain of runs (retries, cron, continue-as-new);
+    // child workflows are separate executions, so this fast_forward won't affect them.
+    google.protobuf.Duration fast_forward = 2;


should we document the behavior when you override the existing fast_forward?

simvlad · 2026-06-10T22:02:52Z

+    reserved 42;
+    reserved "initial_skipped_duration";
+
+  // The time-skipping state propagated from a previous run of this workflow. This can be nil


nit: something is wrong with indentation

Co-authored-by: Spencer Judge <spencer@temporal.io>

feiyang3cat requested review from a team May 22, 2026 22:14

feiyang3cat force-pushed the patch/ts branch 3 times, most recently from 64911c4 to f733324 Compare May 22, 2026 22:42

feiyang3cat force-pushed the patch/ts branch 2 times, most recently from 7431f2f to e24f538 Compare June 1, 2026 02:13

feiyang3cat changed the title ~~[don't merge] just for review~~ [don't merge] need review and server PR Jun 1, 2026

feiyang3cat force-pushed the patch/ts branch from e24f538 to 55a4896 Compare June 1, 2026 04:22

feiyang3cat changed the title ~~[don't merge] need review and server PR~~ [don't merge] time skipping sleep: need review and server PR Jun 1, 2026

feiyang3cat force-pushed the patch/ts branch 3 times, most recently from ae2e298 to a95915b Compare June 1, 2026 17:29

feiyang3cat commented Jun 2, 2026

View reviewed changes

Comment thread temporal/api/workflow/v1/message.proto Outdated

GregoryTravis reviewed Jun 2, 2026

View reviewed changes

JLDLaughlin reviewed Jun 2, 2026

View reviewed changes

Comment thread openapi/openapiv2.json Outdated

feiyang3cat force-pushed the patch/ts branch 2 times, most recently from 1592217 to 2e87466 Compare June 6, 2026 01:09

feiyang3cat mentioned this pull request Jun 6, 2026

(WIP) TS: fast forward and propagation policy change temporalio/temporal#10576

Open

5 tasks

feiyang3cat changed the title ~~[don't merge] time skipping sleep: need review and server PR~~ time skipping fast forward Jun 8, 2026

Sushisource reviewed Jun 8, 2026

View reviewed changes

feiyang3cat force-pushed the patch/ts branch from 480478b to 5643734 Compare June 8, 2026 19:12

simvlad reviewed Jun 8, 2026

View reviewed changes

feiyang3cat force-pushed the patch/ts branch 7 times, most recently from b7654bb to e1c61ec Compare June 10, 2026 16:58

simvlad approved these changes Jun 10, 2026

View reviewed changes

feiyang3cat and others added 4 commits June 10, 2026 19:43

refactor time skipping config and event

db2b458

change sleep to fast forward

9b90b82

comment refinements

c416e58

Co-authored-by: Spencer Judge <spencer@temporal.io>

add TimeSkippingStatePropagation

2f5e4df

feiyang3cat force-pushed the patch/ts branch 3 times, most recently from f38185a to b73490d Compare June 11, 2026 04:06

add explanation for fast-forward override

516bd27

feiyang3cat force-pushed the patch/ts branch from b73490d to 516bd27 Compare June 11, 2026 04:10

add description to fast forward

a095984

feiyang3cat force-pushed the patch/ts branch from 0ed3ac0 to a095984 Compare June 11, 2026 21:01

move time skipping config from workflow folder to the common folder

76e5a37

feiyang3cat force-pushed the patch/ts branch from d1d5fa8 to 4769aed Compare June 13, 2026 05:16

refined the comment for WorkflowExecutionOptions

c5d728b

feiyang3cat force-pushed the patch/ts branch from 4769aed to c5d728b Compare June 13, 2026 05:17

	// When true, time skipping has been disabled automatically due to the fast_forward completing.
	// When true, time skipping has been disabled automatically due to a call to fast_forward completing.

Conversation

feiyang3cat commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

feiyang3cat Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simvlad left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

feiyang3cat commented May 22, 2026 •

edited

Loading

feiyang3cat Jun 8, 2026 •

edited

Loading